Building Qt Creator for HarmonyOS

Qt Creator runs on HarmonyOS devices, such as tablets, as an application package. On the device, it can build applications and run and debug them. The scripts in scripts/harmonyos in the Qt Creator sources build two packages:

qtcreator.hap, which holds Qt Creator, its plugins, and the tools it executes on the device. Those come in a native package, qtctools.hnp, because the device executes nothing that an application writes itself.
qtcrunner.hap, which runs what Qt Creator builds on the device. From its sandbox, Qt Creator cannot install or start an application package. Instead, it hands the application over to this package, which loads it.

The build runs in a Docker image that the scripts create locally. It holds only the host tools, so the result does not depend on the machine that it runs on.

Requirements

The build has been tested on Linux on x86_64. It needs:

Docker and Python 3.
Network access. The scripts download the Ubuntu base image, the Ubuntu packages, and the sources of the libraries and tools that they build. The sources are pinned to fixed versions.
Qt for HarmonyOS from the Qt Online Installer, with the desktop Qt of the same version installed beside it. For example, ~/Qt/6.12.0/harmonyos_arm64_v8a and ~/Qt/6.12.0/gcc_64. The tools that the build runs on the host must come from the same Qt sources as the libraries, so the scripts check for the sha1s.txt file beside them.
The HarmonyOS command-line tools of the SDK version that the application template of the Qt for HarmonyOS names. Qt 6.12 requires 6.1.0(23), which the command-line tools 6.1.0.850 carry. Download Command Line Tools for Linux from the HUAWEI Developer download page. The scripts take the downloaded zip file as it is and unpack it into the output directory once.
Optionally, the device-hosted native SDK, which is published as native-ohos-x64. Without it, the scripts download a pinned OpenHarmony SDK build that contains it.
The material for signing the packages: a keystore, a file that holds the passphrase of the keystore and its key, and a profile and a certificate for each package. The two packages have different bundle names, so they need different profiles. Debug profiles from AppGallery Connect are enough, and they need no ACL permissions. Each profile must list the devices that the package is installed on. Without signing material, the scripts build the packages but leave them unsigned, and a device does not install unsigned packages.

Building the Packages

To build both packages, enter:

 scripts/harmonyos/build_creator_for_harmonyos.py \
     --qt ~/Qt/6.12.0/harmonyos_arm64_v8a \
     --sdk <command-line tools zip, or the directory it was unpacked into> \
     --path <output directory> \
     --keystore <keystore.p12> --key-alias <alias> \
     --keystore-password-file <file> \
     --profile <profile.p7b> --certificate <certificate.cer> \
     --runner-profile <profile.p7b> --runner-certificate <certificate.cer> \
     --runner-bundle <bundle name>

The script runs the following stages in order. Each stage is a script in the same directory, which you can also run on its own:

Stage	Script	Result in the output directory
`packages`	`install_third_party.py`	The libraries that Qt needs at runtime, such as ICU and fontconfig, in `packages/arm64-ohos`.
`tools`	`build_qt_tools.py`	The Qt tools that Qt Creator runs on the device, in `tools`.
`creator`	`build_creator.py`	The Qt Creator build, in `creator`.
`toolchain`	`build_device_toolchain.py`	The compiler, CMake, Ninja, and debugger that Qt Creator builds and debugs with on the device, in `toolchain`. Without this stage, Qt Creator runs on the device but cannot build there.
`hap`	`build_hap.py`	`qtcreator.hap`, or `qtcreator-unsigned.hap`.
`runner`	`build_runner_hap.py`	`qtcrunner.hap`, or `qtcrunner-unsigned.hap`.

The output directory needs about 21 GB, 6.4 GB of which are the command-line tools when --sdk is the zip file.

To run only some stages, list them in --stages. A later run reuses what an earlier one left in the output directory, so after the first run, a stage takes little time unless its inputs changed.

Installing the Packages

To install the packages on a device that hdc is connected to, enter:

 hdc install -r <output directory>/qtcreator.hap
 hdc install -r <output directory>/qtcrunner.hap

For hdc to install them, the device must be in developer mode, and the profiles that the packages are signed with must list the device.

Starting Qt Creator on the Device

To start Qt Creator from hdc, enter:

 hdc shell aa start -a QAbility -b <bundle name>

The bundle name is the one that you passed in --bundle, which is org.qtproject.qtcreator by default.

Building, Running, and Debugging on the Device

When Qt Creator starts on the device, it adds the device itself as HarmonyOS Build Device (This Device) and creates a kit for it. The kit uses the compiler, CMake, and LLDB from the toolchain stage and the Qt that the package holds, so a package built without that stage has no kit to build with.

When you run or debug an application, Qt Creator hands it over to the runner, so qtcrunner.hap must be installed on the device as well. To stop the application, stop it in Qt Creator as usual.

Controlling Qt Creator over MCP

For development, Qt Creator on the device can run its MCP server, so that an agent or a script on the host can drive it. To start the server on a port, pass --mcp-port to the build script. The package then starts Qt Creator with the McpServer plugin loaded and its ui_* tools turned on.

The server only accepts requests that carry its token. Pass a file that holds the token in --mcp-token-file, or let the script write a new token into qtcreator.mcp-token beside the package. Anyone on the device can read the arguments that the token is passed in, so do not use MCP packages outside development.

To reach the server from the host, forward the port with hdc:

 hdc fport tcp:<port> tcp:<port>

Then send the requests to http://127.0.0.1:<port>/ with the token in an Authorization: Bearer header.

Contents